chrome-devtools-frontend 1.0.1367881 → 1.0.1376716

package/.vscode/extensions.json

@@ -1,7 +1,7 @@
 {
   "recommendations": [
-      "dbaeumer.vscode-eslint",
-      "bierner.lit-html",
-      "npclaudiu.vscode-gn"
+    "dbaeumer.vscode-eslint",
+    "runem.lit-plugin",
+    "npclaudiu.vscode-gn"
   ]
-}
+}

package/config/gni/devtools_grd_files.gni

@@ -60,6 +60,7 @@ grd_files_release_sources = [
   "front_end/Images/bundle.svg",
   "front_end/Images/button-magic.svg",
   "front_end/Images/calendar-today.svg",
+  "front_end/Images/center-focus-weak.svg",
   "front_end/Images/check-circle.svg",
   "front_end/Images/check-double.svg",
   "front_end/Images/checker.svg",
@@ -149,6 +150,8 @@ grd_files_release_sources = [
   "front_end/Images/heap-snapshot.svg",
   "front_end/Images/heap-snapshots.svg",
   "front_end/Images/help.svg",
+  "front_end/Images/history.svg",
+  "front_end/Images/home.svg",
   "front_end/Images/hover.svg",
   "front_end/Images/iframe-crossed.svg",
   "front_end/Images/iframe.svg",
@@ -382,11 +385,18 @@ grd_files_release_sources = [
   "front_end/models/issues_manager/descriptions/SameSiteWarnCrossDowngradeSet.md",
   "front_end/models/issues_manager/descriptions/SameSiteWarnStrictLaxDowngradeStrict.md",
   "front_end/models/issues_manager/descriptions/arInsecureContext.md",
+  "front_end/models/issues_manager/descriptions/arInvalidInfoHeader.md",
   "front_end/models/issues_manager/descriptions/arInvalidRegisterOsSourceHeader.md",
   "front_end/models/issues_manager/descriptions/arInvalidRegisterOsTriggerHeader.md",
   "front_end/models/issues_manager/descriptions/arInvalidRegisterSourceHeader.md",
   "front_end/models/issues_manager/descriptions/arInvalidRegisterTriggerHeader.md",
+  "front_end/models/issues_manager/descriptions/arNavigationRegistrationUniqueScopeAlreadySet.md",
   "front_end/models/issues_manager/descriptions/arNavigationRegistrationWithoutTransientUserActivation.md",
+  "front_end/models/issues_manager/descriptions/arNoRegisterOsSourceHeader.md",
+  "front_end/models/issues_manager/descriptions/arNoRegisterOsTriggerHeader.md",
+  "front_end/models/issues_manager/descriptions/arNoRegisterSourceHeader.md",
+  "front_end/models/issues_manager/descriptions/arNoRegisterTriggerHeader.md",
+  "front_end/models/issues_manager/descriptions/arNoWebOrOsSupport.md",
   "front_end/models/issues_manager/descriptions/arOsSourceIgnored.md",
   "front_end/models/issues_manager/descriptions/arOsTriggerIgnored.md",
   "front_end/models/issues_manager/descriptions/arPermissionPolicyDisabled.md",
@@ -469,6 +479,7 @@ grd_files_release_sources = [
   "front_end/models/issues_manager/descriptions/genericResponseWasBlockedByORB.md",
   "front_end/models/issues_manager/descriptions/heavyAd.md",
   "front_end/models/issues_manager/descriptions/mixedContent.md",
+  "front_end/models/issues_manager/descriptions/placeholderDescriptionForInvisibleIssues.md",
   "front_end/models/issues_manager/descriptions/propertyRuleInvalidNameIssue.md",
   "front_end/models/issues_manager/descriptions/propertyRuleIssue.md",
   "front_end/models/issues_manager/descriptions/sharedArrayBuffer.md",
@@ -661,6 +672,7 @@ grd_files_release_sources = [
   "front_end/third_party/diff/diff.js",
   "front_end/third_party/i18n/i18n.js",
   "front_end/third_party/intl-messageformat/intl-messageformat.js",
+  "front_end/third_party/json5/json5.js",
   "front_end/third_party/lighthouse/lighthouse-dt-bundle.js",
   "front_end/third_party/lighthouse/report/report.js",
   "front_end/third_party/lit/lit.js",
@@ -672,6 +684,7 @@ grd_files_release_sources = [
   "front_end/third_party/web-vitals/web-vitals.js",
   "front_end/ui/components/adorners/adorners.js",
   "front_end/ui/components/buttons/buttons.js",
+  "front_end/ui/components/cards/cards.js",
   "front_end/ui/components/chrome_link/chrome_link.js",
   "front_end/ui/components/code_highlighter/code_highlighter.js",
   "front_end/ui/components/data_grid/data_grid.js",
@@ -790,6 +803,7 @@ grd_files_debug_sources = [
   "front_end/core/protocol_client/NodeURL.js",
   "front_end/core/root/Runtime.js",
   "front_end/core/sdk/AccessibilityModel.js",
+  "front_end/core/sdk/AnimationModel.js",
   "front_end/core/sdk/AutofillModel.js",
   "front_end/core/sdk/CPUProfileDataModel.js",
   "front_end/core/sdk/CPUProfilerModel.js",
@@ -844,6 +858,7 @@ grd_files_debug_sources = [
   "front_end/core/sdk/PerformanceMetricsModel.js",
   "front_end/core/sdk/PreloadingModel.js",
   "front_end/core/sdk/ProfileTreeModel.js",
+  "front_end/core/sdk/RehydratingConnection.js",
   "front_end/core/sdk/RehydratingObject.js",
   "front_end/core/sdk/RemoteObject.js",
   "front_end/core/sdk/Resource.js",
@@ -1022,6 +1037,7 @@ grd_files_debug_sources = [
   "front_end/models/trace/extras/FilmStrip.js",
   "front_end/models/trace/extras/MainThreadActivity.js",
   "front_end/models/trace/extras/Metadata.js",
+  "front_end/models/trace/extras/ThirdParties.js",
   "front_end/models/trace/extras/URLForEntry.js",
   "front_end/models/trace/handlers/AnimationHandler.js",
   "front_end/models/trace/handlers/AuctionWorkletsHandler.js",
@@ -1115,9 +1131,7 @@ grd_files_debug_sources = [
   "front_end/panels/accessibility/accessibilityNode.css.js",
   "front_end/panels/accessibility/accessibilityProperties.css.js",
   "front_end/panels/accessibility/axBreadcrumbs.css.js",
-  "front_end/panels/animation/AnimationDOMNode.js",
   "front_end/panels/animation/AnimationGroupPreviewUI.js",
-  "front_end/panels/animation/AnimationModel.js",
   "front_end/panels/animation/AnimationScreenshotPopover.js",
   "front_end/panels/animation/AnimationTimeline.js",
   "front_end/panels/animation/AnimationUI.js",
@@ -1391,9 +1405,9 @@ grd_files_debug_sources = [
   "front_end/panels/freestyler/FreestylerEvaluateAction.js",
   "front_end/panels/freestyler/FreestylerPanel.js",
   "front_end/panels/freestyler/components/FreestylerChatUi.js",
-  "front_end/panels/freestyler/components/ProvideFeedback.js",
+  "front_end/panels/freestyler/components/UserActionRow.js",
   "front_end/panels/freestyler/components/freestylerChatUi.css.js",
-  "front_end/panels/freestyler/components/provideFeedback.css.js",
+  "front_end/panels/freestyler/components/userActionRow.css.js",
   "front_end/panels/freestyler/freestylerPanel.css.js",
   "front_end/panels/issues/AffectedBlockedByResponseView.js",
   "front_end/panels/issues/AffectedCookiesView.js",
@@ -1502,7 +1516,6 @@ grd_files_debug_sources = [
   "front_end/panels/network/NetworkSearchScope.js",
   "front_end/panels/network/NetworkTimeCalculator.js",
   "front_end/panels/network/NetworkWaterfallColumn.js",
-  "front_end/panels/network/RequestBinaryResponseView.js",
   "front_end/panels/network/RequestCookiesView.js",
   "front_end/panels/network/RequestHTMLView.js",
   "front_end/panels/network/RequestInitiatorView.js",
@@ -1656,10 +1669,11 @@ grd_files_debug_sources = [
   "front_end/panels/search/SearchView.js",
   "front_end/panels/search/searchResultsPane.css.js",
   "front_end/panels/search/searchView.css.js",
+  "front_end/panels/security/CookieReportTreeElement.js",
   "front_end/panels/security/OriginTreeElement.js",
-  "front_end/panels/security/SecurityAndPrivacyPanelSidebar.js",
   "front_end/panels/security/SecurityModel.js",
   "front_end/panels/security/SecurityPanel.js",
+  "front_end/panels/security/SecurityPanelSidebar.js",
   "front_end/panels/security/SecurityPanelSidebarTreeElement.js",
   "front_end/panels/security/lockIcon.css.js",
   "front_end/panels/security/mainView.css.js",
@@ -1785,8 +1799,6 @@ grd_files_debug_sources = [
   "front_end/panels/timeline/components/BreadcrumbsUI.js",
   "front_end/panels/timeline/components/CPUThrottlingSelector.js",
   "front_end/panels/timeline/components/DetailsView.js",
-  "front_end/panels/timeline/components/EntryName.js",
-  "front_end/panels/timeline/components/EntryStyles.js",
   "front_end/panels/timeline/components/FieldSettingsDialog.js",
   "front_end/panels/timeline/components/InteractionBreakdown.js",
   "front_end/panels/timeline/components/LayoutShiftDetails.js",
@@ -1853,6 +1865,9 @@ grd_files_debug_sources = [
   "front_end/panels/timeline/timelinePaintProfiler.css.js",
   "front_end/panels/timeline/timelinePanel.css.js",
   "front_end/panels/timeline/timelineStatusDialog.css.js",
+  "front_end/panels/timeline/utils/AICallTree.js",
+  "front_end/panels/timeline/utils/EntryName.js",
+  "front_end/panels/timeline/utils/EntryStyles.js",
   "front_end/panels/timeline/utils/Helpers.js",
   "front_end/panels/timeline/utils/IgnoreList.js",
   "front_end/panels/timeline/utils/ImageCache.js",
@@ -1899,6 +1914,8 @@ grd_files_debug_sources = [
   "front_end/third_party/i18n/i18n-impl.js",
   "front_end/third_party/i18n/localized-string-set.js",
   "front_end/third_party/intl-messageformat/package/intl-messageformat.esm.js",
+  "front_end/third_party/json5/lib/index.js",
+  "front_end/third_party/json5/package/lib/index.js",
   "front_end/third_party/lighthouse/report-assets/report-generator.mjs",
   "front_end/third_party/lighthouse/report/bundle.js",
   "front_end/third_party/lit/lib/decorators.js",
@@ -2127,6 +2144,8 @@ grd_files_debug_sources = [
   "front_end/ui/components/adorners/adorner.css.js",
   "front_end/ui/components/buttons/Button.js",
   "front_end/ui/components/buttons/button.css.legacy.js",
+  "front_end/ui/components/cards/Card.js",
+  "front_end/ui/components/cards/card.css.js",
   "front_end/ui/components/chrome_link/ChromeLink.js",
   "front_end/ui/components/chrome_link/chromeLink.css.js",
   "front_end/ui/components/code_highlighter/CodeHighlighter.js",
@@ -2158,8 +2177,10 @@ grd_files_debug_sources = [
   "front_end/ui/components/helpers/scheduled-render.js",
   "front_end/ui/components/highlighting/HighlightManager.js",
   "front_end/ui/components/highlighting/highlighting.css.js",
+  "front_end/ui/components/icon_button/FileSourceIcon.js",
   "front_end/ui/components/icon_button/Icon.js",
   "front_end/ui/components/icon_button/IconButton.js",
+  "front_end/ui/components/icon_button/fileSourceIcon.css.js",
   "front_end/ui/components/icon_button/icon.css.legacy.js",
   "front_end/ui/components/icon_button/iconButton.css.js",
   "front_end/ui/components/input/checkbox.css.js",
@@ -2386,6 +2407,7 @@ grd_files_debug_sources = [
   "front_end/ui/legacy/components/source_frame/PreviewFactory.js",
   "front_end/ui/legacy/components/source_frame/ResourceSourceFrame.js",
   "front_end/ui/legacy/components/source_frame/SourceFrame.js",
+  "front_end/ui/legacy/components/source_frame/StreamingContentHexView.js",
   "front_end/ui/legacy/components/source_frame/XMLView.js",
   "front_end/ui/legacy/components/source_frame/fontView.css.legacy.js",
   "front_end/ui/legacy/components/source_frame/imageView.css.legacy.js",

package/config/gni/devtools_image_files.gni

@@ -67,6 +67,7 @@ devtools_svg_sources = [
   "bundle.svg",
   "button-magic.svg",
   "calendar-today.svg",
+  "center-focus-weak.svg",
   "check-circle.svg",
   "check-double.svg",
   "checker.svg",
@@ -152,6 +153,8 @@ devtools_svg_sources = [
   "heap-snapshot.svg",
   "heap-snapshots.svg",
   "help.svg",
+  "history.svg",
+  "home.svg",
   "hover.svg",
   "iframe-crossed.svg",
   "iframe.svg",

package/docs/README.md

@@ -27,12 +27,8 @@ below.**
 *   [Contribution Guide](./contributing/README.md)
 *   [UX Style Guide](./styleguide/ux/README.md)
 *   [Testing Guide](../test/README.md)
-*   [Release Management](release_management.md)
-*   [Dependencies](dependencies.md)
-*   [Localization](l10n.md)
+*   [Cookbook](./cookbook/README.md)
 *   [Visual logging in DevTools](../front_end/ui/visual_logging/README.md)
-*   [UMA metrics in DevTools](uma_metrics.md)
-    *   [How to add UMA metrics in DevTools frontend](add_uma_metrics.md)
 *   [Style Guides](./styleguide/README.md)
 
 ### Architectural Documentation

package/docs/checklist/javascript.md

@@ -76,9 +76,6 @@ as expression position for the exception. For syntax errors, we should report th
 Note that `Error.stack` is only collected for `Error` objects, at the time the `Error` object is constructed. This may be different
 than the stack trace passed to DevTools via [`JSMessageObject`](https://source.chromium.org/chromium/chromium/src/+/main:v8/src/objects/js-objects.h;l=1264-1345;drc=82dff63dbf9db05e9274e11d9128af7b9f51ceaa).
 
-Independently from V8, DevTools offers a way to show async stack traces by stitching together stack traces collected at the
-location where the callback is passed, and the actual location of the exception inside the callback.
-
 ### Affected
 
 NLFs that can cause an exception to be thrown, or can call into another function that throws.
@@ -95,12 +92,34 @@ Repeat with the "Disable async stack traces" checkbox in the Preferences checked
 Test cases for stack traces is mandatory, if there is any way the NLF can interact with throwing exceptions. For examples look
 for `mjsunit` tests with `stack-trace` in their names.
 
-For async stack traces, please look at Blink LayoutTests such as [this one](https://chromium.googlesource.com/chromium/src/+/3daa588ce613845e298cbd667fa6f5787f95d574/third\_party/WebKit/LayoutTests/inspector/sources/debugger-async/async-await/async-callstack-async-await.html).
-
 ### Reading material
 
 [Design doc for debugging support for tail-calls](https://docs.google.com/a/google.com/document/d/1Bk4QahtaT-XzrMlHTkm0SVol3LoKXTrC9E7INxJBHrE/edit?usp=drive\_web)
 
+## Async stack traces
+
+DevTools offers a way to show async stack traces by stitching together stack traces collected at the
+location where the callback is passed, and the actual location of the exception inside the callback.
+
+The canonical example of this is throwing inside a `setTimeout` callback. The async stack trace will
+consist of the stack trace of the error plus a stack trace captured at the `setTimeout` call-site.
+
+The instrumentation is based on four [`ayncTask*` methods](https://source.chromium.org/chromium/chromium/src/+/main:v8/include/v8-inspector.h;l=370-375;drc=aafd25ffbc72935b52fee731f957e5827c73a096). Namely `asyncTaskScheduled`, `asyncTaskStarted`, `asyncTaskFinished` and `asyncTaskCancelled`.
+V8 has a [higher-level interface](https://source.chromium.org/chromium/chromium/src/+/main:v8/src/debug/debug-interface.h;l=351-352;drc=e6fc2038d73ef96ff47deda3146d94d25530e13b) that translates Promise events (such as `await`, `.then`, etc) to these for `asyncTask*` methods.
+
+### Affected
+
+NLFs touching promises or callback scheduling.
+
+### How to test
+
+Throw or pause inside a new language feature and check either the call stack sidebar panel in "Sources"
+or use a `console.trace` and check the async stack trace in the console.
+
+### Test cases
+
+Test cases for async stack traces are mandatory, if there is any way the NLF interacts with callback scheduling or
+Promises. For examples look in V8 `inspector` tests with `async-stack` in their name (e.g. [here](https://source.chromium.org/chromium/chromium/src/+/main:v8/test/inspector/debugger/async-stack-await.js)).
 
 ## Catch prediction
 
@@ -319,11 +338,30 @@ Take a heap Snapshot in DevTools' Profiler panel and inspect the result. Objects
 
 Take a look at `test/cctest/test-heap-profiler.cc`.
 
+## Restart frame
+
+DevTools allows restarting of some stack frames, not just the top-level one. The feature is implemented by throwing a termination exception and unwinding the stack
+until after the function we want to restart, and then re-invoking the function. This only works for certain functions, e.g. async functions can't be restarted
+as that would require rolling back the underlying generator.
+
+### Affected
+
+NLFs that change function execution or require a function to carry state (e.g. async functions
+need a generator that can't be reset).
+
+### How to test
+
+While paused, right click a stack frame with the NLF in the call stack view and select "Restart frame". If the NLF prevents the frame from being restarted, then
+the "Restart frame" menu item must be disabled, otherwise the frame must be properly restarted.
+
+### Test cases
+
+Take a look in `test/inspector/debugger/restart-frame/*`.
 
 ## LiveEdit
 
 LiveEdit is a feature that allows for script content to be replaced during its execution. While it has many limitations, the most often use case
-of editing the function we are paused in and restarting said function usually works.
+of editing the function we are paused in and restarting said function afterwards.
 
 ### Affected
 
@@ -331,8 +369,7 @@ NLFs that affect code execution
 
 ### How to test
 
-Open DevTools and break inside the part of script affected by the NLF. In the Source panel's Call Stack view, right-click the top-most frame and select
-Restart Frame.
+Open DevTools and break inside the part of script affected by the NLF. Change the code inside the function with the NLF and save the script.
 
 ### Test cases
 

package/docs/contributing/design.md

@@ -39,7 +39,7 @@ be send to
 [devtools-dev+design@chromium.org](mailto:devtools-dev+design@chromium.org).
 
 Google internal design docs have to live in the
-[Design Documents (internal)](https://drive.google.com/corp/drive/folders/15oHN9vX8j08QOkegjWKdSN0XjyaoLanl)
+[Design Documents (internal)](http://go/chrome-devtools:design-internal-drive)
 folder of the shared internal
 [Chrome DevTools](http://go/chrome-devtools/team-resources#chrome-devtools-shared-drive) team drive, and
 should be sent to

package/docs/contributing/settings-experiments-features.md

@@ -97,7 +97,7 @@ Chromium.
 
 ### Define a new `base::Feature`
 
-Add a new `base::Feature` to [`browser_features.cc`](https://crsrc.org/c/chrome/browser/browser_features.cc). This feature will automatically be available as a Chrome command line parameter:
+Add a new `base::Feature` to DevTools' [`features.cc`](https://crsrc.org/c/chrome/browser/devtools/features.cc). This feature will automatically be available as a Chrome command line parameter:
 
 ```cxx
 // in browser_features.cc

package/docs/cookbook/README.md

@@ -0,0 +1,12 @@
+# Chromium DevTools Cookbook
+
+[goo.gle/devtools-cookbook](http://goo.gle/devtools-cookbook)
+
+The cookbook provides *recipes* for common workflows / tasks during development
+of Chromium DevTools itself.
+
+*   [Create new Issues in DevTools](create_new_issues.md)
+*   [Dependencies](dependencies.md)
+*   [Localization](localization.md)
+*   [Release Management](release_management.md)
+*   [UMA metrics in DevTools](uma_metrics.md)

package/docs/cookbook/create_new_issues.md

@@ -0,0 +1,91 @@
+# Create new Issues in DevTools
+
+[TOC]
+
+The goal of this doc is to guide you through the necessary steps to send
+messages to the new
+[Issues panel](https://developers.google.com/web/updates/2020/05/devtools#issues)
+([Design Doc](https://docs.google.com/document/u/1/d/1F6R5Bpb3qHNzGPNBSXwEJ_eP8L-anIj0WinxOIyAh54)).
+This will help reduce the console fatigue and will give more context to
+developers on what the problem is, why it should be fixed and how it can be
+fixed.
+
+## Why the Issues Panel?
+
+If there is an existing console log that for some reason you want to edit, this
+is a good opportunity to re-think how actionable this message is for developers.
+If you are working on a feature and you have in mind throwing a new console log
+to notify developers of an unexpected behavior, think about showing an Issue
+instead.
+
+Developers could be missing your warning due to the clutter in the console
+caused by the many different messages. By creating a new Issue type, you will
+give more context on the problem and make the debugging experience more
+actionable for them.
+
+## Create new or move existing console messages to the Issues panel
+
+To do so, follow the next steps:
+
+*   Reach-out to [dsv@](mailto:dsv@chromium.org) (DevTools TL) and share the
+    related design doc. Every Issue should be actionable and have at least one
+    straightforward solution. With the addition of more context and external
+    documentation, it will support the developer across the whole debugging
+    story, making the message more actionable than in the console.
+*   Pipe your message into DevTools. First you need to decide which additional
+    information you want to send with your issue. Depending on the answer
+    you'll have two options:
+    1) Use the [generic issue](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/devtools_protocol/browser_protocol.pdl;l=807-829;drc=3e4a3b72cdd0cab0224292a7322ff3cf0248d307). This is the easier option.
+    All that is required is to add a new value to `GenericIssueErrorType`.
+    Generic issue allows sending along some pre-defined additional information:
+    Frame ids, network requests and DOM node ids among others.
+    2) If a generic issue is not enough, you can introduce a domain/problem
+    specific issue type. See [here](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/devtools_protocol/browser_protocol.pdl;l=666;drc=bc268cf81e62349e0f283107d70a5f742476ef4e)
+    how other issues are defined. You need to add an issue code and an issue
+    details definition. The issue details should hold all the information
+    that is required for reporting the issue in the front-end.
+*   Next, you need to figure out where to report the issue.
+    Issues can be reported on the browser side (choose this if the
+    issue is raised in content/browser and/or has information that should not be
+    shared with the renderer). Otherwise you can report it in the renderer.
+    *   For Browser-side reporting, use
+        [`devtools_instrumentation::ReportBrowserInitiatedIssue`](https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_instrumentation.cc;l=1981;drc=10c26d0d230900f91d239f2fe0b731b054127e89)
+        to report the issue.
+    *   For renderer-side reporting, use an `AddInspectorIssue` method, those
+        are available at every execution context, plus some more classes.
+        ([example](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/bindings/core/v8/isolated_world_csp.cc;l=107;drc=d2b5c17eff35da6ebff8ba20c99688b87e1bc752)).
+*   Depending on where the issue is reported, creating the protocol structures
+    works differently.
+    *   An example of how to create the data-structure can be found
+    *   [here](https://source.chromium.org/chromium/chromium/src/+/3564e4bcc7d53aa60350794fc1348792cc33c80d:content/browser/devtools/devtools_instrumentation.cc;drc=d6edf4bb211798b0aa0b656dfb06614cfea043e3;l=181)
+        for the browser side
+    *   [here](https://source.chromium.org/chromium/chromium/src/+/3564e4bcc7d53aa60350794fc1348792cc33c80d:third_party/blink/renderer/core/inspector/inspector_audits_agent.cc;drc=2decd986a617ab2556ac268e4c2ef156ac8f7361;l=431)
+        for the renderer side
+*   Please add the corresponding backend and frontend test for your changes.
+    *   [Example](https://chromium-review.googlesource.com/c/chromium/src/+/2485937)
+        of a CL introducing backend web\_tests.
+    *   [Example](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2485086)
+        of a CL introducing frontend E2E tests.
+*   Please CC [szuend@](mailto:szuend@chromium.org) in your CL, and/or add them
+    as reviewers. You should aim at landing your CL at least 2 weeks before the
+    Branch cut. Feel free to send out the CL even if it is in an early stage.
+    The DevTools team can point you in the right direction, and this will avoid
+    last minute surprises.
+*   Draft the issue strings (find a template below) and share them with
+    [dsv@](mailto:dsv@chromium.org) and the rest of your team for approval.
+*   Once the issue strings are reviewed, implement the front-end CL following
+    [this example](https://crrev.com/c/2308536). Please add
+    [szuend@](mailto:szuend@chromium.org) as reviewers to your CL, and send it
+    out early to get quick feedback. We are happy to help you iterate.
+*   Please add UMA tracking for your new issue types. This is as easy as adding
+    the issue types to an enum
+    ([frontend example CL](https://crrev.com/c/2692913),
+    [backend example CL](https://crrev.com/c/2694408)).
+
+## Draft Issue strings
+
+To create the UX strings the best approach is to draft an initial proposal and
+then share it with the broader team for polishing
+([existing issue descriptions](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/issues/descriptions/)
+for reference). You can wordsmith the issue description in a separate docs or
+directly in the CL with Gerrit.

package/docs/cookbook/dependencies.md

@@ -0,0 +1,103 @@
+# Dependencies
+
+[TOC]
+
+## Managing dependencies
+
+If you need to manually roll a git dependency, it's not sufficient to update the
+revision in the DEPS file. Instead, use the gclient tool: `bash gclient setdep
+-r DEP@REV # for example build@afe0125ef9e10b400d9ec145aa18fca932369346` This
+will simultaneously update both the DEPS entry as well as the gitlink entry for
+the corresponding git submodule.
+
+To sync dependencies from Chromium to DevTools frontend, use
+`scripts/deps/roll_deps.py`. Note that this may: - Introduce unneeded
+whitespace/formatting changes. Presubmit scripts (e.g. invoked via `git cl
+upload`) will automatically fix these locally, so just apply the changes
+directly to your change (e.g. with `git commit --amend`) afterwards. - Introduce
+breaking changes to the devtools protocol, causing compilation failures.
+Unfortunately these need to be handled manually as there are some changes (e.g.
+removing an enum value) that cannot fail gracefully.
+
+The following scripts run as AutoRollers, but can be manually invoked if
+desired:
+
+-   To roll the `HEAD` commit of DevTools frontend into Chromium, use
+    `scripts/deps/roll_to_chromium.py`.
+-   To update DevTools frontend's DEPS, use `roll-dep`.
+
+## Third-party Guidelines
+
+When you want to integrate or use third-party content in DevTools, there are a
+couple of different ways to do so. Most of the time, we have to make a
+distinction between "third-party code we use as part of DevTools implementation"
+and "third-party code we use to build DevTools itself, but is not included in
+the product".
+
+### Third-party code included in DevTools bundle
+
+All third-party content that you want to ship as part of the DevTools bundle
+must be included in `front_end/third_party`. The typical way to update these
+packages is to download the relevant packages from [npm]. Since DevTools does
+not use a `package.json` to handle its dependencies (to make it possible to
+review third-party changes by legal), most packages bundles are fetched with
+`wget`.
+
+For all these packages, the [Chromium third-party guidelines] apply.
+
+Since DevTools ships as part of the Chrome binary, bundle size limitations
+apply. To make integration feasible, focus on small packages that (preferably)
+have no dependencies. This will make licensing checks feasible for Chromium
+reviewers and typically avoids inflating the bundle size.
+
+### Third-party tooling packages
+
+For all third-party packages that are used either as part of the DevTools build
+process or to augment engineers workflows (for example linters), we add them to
+`scripts/deps/manage_node_deps.py`. This Python script has been approved by
+Chromium licensing to be used, on the basis that it enforces all packages have a
+license that is compatible with a set of pre-defined licensees.
+
+If you want to use a new package as tooling process in engineer workflows, you
+can add the package to the `package.json` and run `npm run install-deps` to
+check in the new contents.
+
+Only add new license types to `LICENSES` after you received approval from
+`opensource-licensing@google.com`. Their response time is typically within 24
+hours, so this typically is not a big hurdle.
+
+To avoid excessive package updates, it is typically easiest to update all
+packages in `manage_node_deps.py` once a month. Since NPM packages can have a
+lot of (shared) transitive dependencies, updating the packages on a specific day
+increases the chances that shared dependencies are deduplicated and thus result
+in smaller repository sizes.
+
+> **WARNING:** Updating tools such as Rollup and TypeScript will cause all build
+> cache output to be purged, as they are part of all DevTools modules. Whenever
+> you are updating either of these tools, update these at the end of a working
+> day to avoid full rebuilds for other engineers.
+
+### Chromium third-party DEPS
+
+Some packages related to infrastructure are maintained by Chromium infra teams.
+These packages are typically uploaded to cloud storage buckets or are explicitly
+mirrored to a repository on https://chromium.googlesource.com. Examples include
+[GN][] (Chromium/DevTools build system) or [clang-format][] (multi-language
+formatter).
+
+The packages in `DEPS` are typically kept automatically up-to-date with
+autorollers. These autorollers will periodically update packages, which
+engineers can fetch with running `gclient sync`.
+
+These `DEPS` are checked out on all bots, which includes Chromium and
+DevTools-specific bots. To avoid excessive network bandwidth usage, by default
+do not check out packages if they are only used in specific situations.
+
+Only include packages that are maintained by Chromium infrastructure teams and
+are used to build DevTools in `DEPS`. For packages that are DevTools-specific,
+prefer adding them to `scripts/deps/manage_node_deps.py` instead.
+
+[npm]: https://www.npmjs.com/
+[Chromium third-party guidelines]: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/adding_to_third_party.md
+[GN]: https://gn.googlesource.com/gn/+/master/docs/reference.md
+[clang-format]: https://clang.llvm.org/docs/ClangFormat.html